Skip to content

fix: diagnose unified connection services - #9680

Merged
Hui Miao (huimiu) merged 9 commits into
mainfrom
hui/connection-diagnostics-pr
Aug 25, 2026
Merged

fix: diagnose unified connection services#9680
Hui Miao (huimiu) merged 9 commits into
mainfrom
hui/connection-diagnostics-pr

Conversation

@huimiu

@huimiu Hui Miao (huimiu) commented Aug 21, 2026

Copy link
Copy Markdown
Member

Why this is needed

Issue #8710 needs Doctor and next step to diagnose configured Foundry connections consistently across the current unified format and older projects. The collector must honor the same source selection and precedence used by provisioning so enabled connections are not skipped or reported with the wrong remote result. Configuration errors also need to stop remote.connections before any Foundry probe runs.

Why this approach

The collector now follows provisioning's compatibility selection: it first reads enabled standalone azure.ai.connection services. Only when no enabled standalone connection is found and no unified configuration load error occurred does it fall back to bundled agent connections, then legacy manifest resources. These compatibility sources are intentionally not merged with an active unified source; within fallback mode, bundled data takes precedence over legacy manifests for duplicate names. It deduplicates and sorts results, while keeping credentials and metadata out of diagnostics. Doctor reports connection load errors before probing, skips when there are no enabled connections, and recommends azd provision for missing remote connections.

A connection condition belongs at the root of azure.yaml, next to host. A root false condition still wins and short-circuits $ref loading. For an enabled service, or one without a root condition, a condition that comes from resolved $ref content is treated as a configuration error, with guidance to move it beside host. Payload conditions do not override the root field. Whitespace-only conditions count as false.

Malformed legacy manifest strictness and target, credentials, and metadata variable validation are out of scope for this diagnostics-only change.

E2E validation

  • azd ai agent doctor --local-only passed; remote checks remained excluded.
  • azd ai agent doctor passed with an enabled unified connection on the Foundry project; remote.connections passed.
  • azd ai agent doctor with a resolved $ref condition failed as expected, with guidance to place condition beside host in azure.yaml.
  • azd ai agent doctor with root condition: false and whitespace-only conditions passed; connection checks skipped without resolving broken $ref values.

Closes: #9684

@azure-pipelines

Copy link
Copy Markdown
Azure Pipelines:
Successfully started running 1 pipeline(s).
20 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

@github-actions github-actions Bot added the ext-agents azure.ai.agents extension label Aug 21, 2026
@azure-pipelines

Copy link
Copy Markdown
Azure Pipelines:
Successfully started running 1 pipeline(s).
20 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

@github-actions

Copy link
Copy Markdown

📋 Prioritization Note

Thanks for the contribution! The linked issue isn't in the current milestone yet.
Thank you for logging this issue; our team is reviewing it. If you need urgent prioritization, tag Rick Winter (@RickWinter) and Kristen Womack (@kristenwomack) to let us know.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds unified Foundry connection diagnostics across Doctor and next-step state assembly.

Changes:

  • Merges enabled unified, bundled, and legacy connections with precedence and sorting.
  • Reports configuration errors before connection probing.
  • Updates Doctor messaging, resource-ID validation, and tests.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
nextstep/types.go Adds connection load errors to state.
nextstep/state.go Invokes unified connection collection.
nextstep/manifest.go Moves connection collection out of manifest traversal.
nextstep/evaluate.go Adds condition evaluation helpers.
nextstep/connections.go Collects and merges connection sources.
nextstep/connections_test.go Tests collection, conditions, and precedence.
nextstep/condition.go Uses shared condition evaluation.
doctor/checks_remote_test.go Updates check-name assertion.
doctor/checks_connections.go Updates connection diagnostics and validation.
doctor/checks_connections_test.go Expands Doctor behavior coverage.

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/connections.go Outdated
Copilot AI review requested due to automatic review settings August 24, 2026 04:04

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/connections.go:60

  • This always adds bundled connections after split services, but the provisioning path does not use the same merge rule: collectConnections returns as soon as any azure.ai.connection service is present (internal/cmd/resource_services.go:538-540) and ignores all bundled entries. In a partially migrated project, Doctor can report a unique bundled connection as missing and recommend azd provision, although provisioning cannot create it. Align diagnostics with the existing all-or-nothing fallback, or update provisioning to implement the same per-name precedence.
	collectBundledConnections(
		ctx,
		src,
		envName,
		projectCfg,

cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/evaluate.go:73

  • azd treats an explicitly empty condition as absent/enabled (pkg/project/service_config.go:124-125, and internal/project/service_target_agent.go:450-452 does the same), but this branch returns false for condition: "". Doctor can therefore omit a connection that provisioning considers active and incorrectly skip remote.connections. Preserve empty-string-as-enabled while keeping non-empty whitespace-only values false, and update the new test that currently groups both cases together.
	if strings.TrimSpace(value) == "" {
		return false, nil

Copilot AI review requested due to automatic review settings August 24, 2026 07:29

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/connections.go:377

  • Requiring kind drops a supported bundled-configuration shape. collectConnections used by provisioning accepts a ServiceTargetAgentConfig containing connections without an inline agent definition (resource_services_test.go:353-378), but this branch skips that same map and Doctor reports no configured connections or falls back to the manifest. Detect bundled connection config independently of whether the service also carries an inline agent definition, and cover the no-kind legacy config case here.
		if !mapHasKind(resolved) {
			continue
		}

Comment thread cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/connections.go Outdated
Copilot AI review requested due to automatic review settings August 24, 2026 08:01

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/condition.go:73

  • [azd-code-reviewer] When an azd environment is selected, this lookup treats an unset azd value as empty instead of falling back to the process environment. Core provisioning evaluates conditions with environment.Environment.Getenv, which falls back to os.Getenv (pkg/environment/environment.go:188-198), so ${DEPLOY_CONN} can enable and provision a connection while Doctor skips it. Preserve that fallback here so diagnostics use the same enabled-service set as provisioning.
		value, err := src.EnvValue(ctx, envName, name)

Copilot AI review requested due to automatic review settings August 24, 2026 08:34

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

cli/azd/extensions/azure.ai.agents/internal/cmd/doctor/checks_connections.go:138

  • azd-code-reviewer: ConnectionLoadErrors is never populated from agent.manifest.yaml; manifest read and parse failures are intentionally ignored in connections.go:305-312. Directing users to fix that file points at an unrelated source and conflicts with the PR’s stated out-of-scope malformed-legacy handling. Limit this suggestion to azure.yaml and its $ref files.
					Suggestion: "Fix azure.yaml, its $ref files, or the " +
						"legacy agent.manifest.yaml, then retry " +
						"`azd ai agent doctor`.",

@huimiu
Hui Miao (huimiu) merged commit 291129f into main Aug 25, 2026
32 checks passed
@huimiu
Hui Miao (huimiu) deleted the hui/connection-diagnostics-pr branch August 25, 2026 02:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ext-agents azure.ai.agents extension

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve connection diagnostics for unified services

3 participants